Tutoriel express pour l’utilisation de github dans le cadre d’un dépôt de publication Rzine

1 Préambule

1.1 Pourquoi utiliser Github dans le cadre de Rzine

Depuis maintenant plusieurs années en SHS on entend beaucoup parler de Git, Github ou encore Gitlab, il s’agit quasiment d’un passage obligé lorsque l’on parle de traitement de la donnée. Ces outils ont vocation à faciliter le partage et la collaboration autour de projets. Les fonctionnalités proposées permettent notamment le suivi et la comparaison de version et un reviewing efficace.

1.2 Objectif de cette fiche

Si au sein de certaines disciplines, comme notamment en informatique, ce que sont Git et Github et leur fonctionnement est très clair, ça l’est souvent beaucoup moins en sciences humaines. Nous nous proposons ici d’en réaliser une présentation très succincte et de présenter un pas à pas simplifié afin de faciliter la prise en main de ces outils dans le cadre spécifique du dépôt d’une fiche Rzine. Il ne s’agit en aucun cas d’aborder toutes les subtilités et la compléxité de Git.

R ne sera donc ici pas du tout le sujet, et aucune information sur la manière de renseigner une fiche Rzine ne sera donnée. Pour cela, rendez-vous sur la fiche : Référencer une publication sur Rzine

1.3 Glossaire

Ici quelques termes spécifiques à Git qu’il nous a semblé important d’expliciter un minimum.

Brève introduction

Git est un logiciel libre dont le premier développement date de 2005. Créé par Linus Torvald (auteur du noyau Linux), sa fonctionnalité première réside dans la gestion/contrôle de version1.

Git a été conçu dans l’optique de permettre et de faciliter la collaboration entre les individus en intégrant les apports de chacun au projet de façon incrémentale ou synchrone.

Le fonctionnement de Git repose sur des lignes de commande et, vous l’aurez compris, il s’agit du coeur autour duquel se sont dévellopés des outils comme Github et Gitlab.

Github et Gitlab sont à l’origine des sites webs dont l’objectif est de venir renforcer l’aspect collaboratif de Git en proposant des fonctionnalités supplémentaires telles que que la gestion des tickets/issues, les publications/releases, la documentation… Ils offrent également une interface graphique à Git, ce qui permet de s’affranchir -dans une certaine mesure- des lignes de commande sur lesquelles repose Git.

Github et Gitlab permettent globalement la même chose. Toutefois, Gitlab est une alternative open source, qui offre des fonctionnalités plus avancées que Github, qui se positionne quant-à lui comme la référence mondiale popularisé Git et regroupe plusieurs millions d’utilisateurs.

Pas à pas pour la création d’un dépot Github

Dans le cadre de ce tutoriel, nous vous proposons de vous présenter “pas à pas” les étapes suivies pour le dépot de cette fiche sur un compte github. La démarche se fera à la fois en clique-bouton et à l’aide des lignes de commande. Cette fiche a été réalisée via R sous la forme d’un document Rmarkdown, dans un projet R enregistré en local.

1.4 Installation de Git

La première étape consiste à installer Git sur votre ordinateur.

Cela se fait très simplement quelque soit le système d’exploitation de votre machine. Il suffit de suivre les instructions parfaitement détaillées en français sur la page d’installation de Git

1.5 Création d’un compte Github

Il s’agit d’un passage obligé. Si ce fonctionnement peut faire, à raison, penser à celui d’un réseau social, rassurez-vous, les règles de la propriété intellectuelle sont très claires, et vous choisirez les projets à rendre public ou privé, ainsi que les collaborateurs à associer à chaque dépôt.

La création d’un compte se fait de manière tout à fait classique :

  1. Rendez-vous sur le site de Github
  2. Cliquez sur sign up en haut à droite
  3. Remplissez les champs demandés

1.6 Créer un nouveau dépôt Github

Une fois connecté.e à Github, vous arrivez sur la page de votre profil.

Pour créer un dépot2 rendez-vous sur la section Repositories via le bandeau.

Cette page recence tous les répertoires associés à votre compte, si vous venez de vous créer un compte, elle devrait donc être vide, sinon vous retrouverez ici tous vos différents dépôts. Pour en créer un, il suffit de cliquer sur new.

C’est sur cette page -à laquelle vous venez d’accéder après avoir cliqué sur new - que vous allez véritablement créer votre nouveau dépôt : lui donner un nom, déterminer son statut privé ou public, en organiser le contenu…

Après avoir cliqué sur Create repository vous aurez donc créé avec succès un nouveau dépôt Github et devriez voir une nouvelle page s’afficher à l’écran, présentant les principales étapes à suivre pour l’ajout de contenu par le biais d’informations textuelles et de lignes de code.

1.7 Importer des éléments dans votre répertoire Github depuis votre ordinateur

Pour réaliser cet import, vous allez temporairement laisser Github de côté.

Vous avez donc réalisé en local votre fiche Rzine, et disposez d’un dossier contenant tous les différents éléments. L’objectif est donc d’importer facilement ce dossier (dans son intégralité) dans votre répertoire GitHub en utilisant Git et ses lignes de commande classiques.

1- Il vous faut en premier lieu ouvrir votre terminal ou invite de commandes

C’est la façon la plus efficace d’interagir avec Github depuis votre ordinateur. De prime abord, l’interface d’interprétation de commandes peut rebuter les non-initiés, mais les commandes Git se maîtrisent rapidement.

Chaque système d’exploitation possède sa propre interface en ligne de commandes :

  • Windows : l’invite de commandes peut être lancée en utilisant la touche Windows et en tapant Invite de commande (ou cmd) avant de sélectionner l’option dans la liste qui apparaît.
  • MacOS : on lance un terminal depuis l’onglet Applications > Utilitaires.
  • Linux : généralement, on peut lancer un terminal avec le raccourci clavier Ctrl + Alt + T. Si cela ne fonctionne pas, recherchez Terminal dans les applications ou via les outils de recherche.

Voici à quoi ressemble un terminal :

2- Vous allez maintenant vous placer dans le dossier au sein duquel vous avez enregistré le projet que vous souhaitez importer via la ligne de commande :

cd "chemin/vers/votre/dossier"

Il faudra bien sur remplacer le chemin entre "" par le chemin correspondant à votre dossier sur votre ordinateur.

3- Il faut ensuite lancer Git :

git init

Cette commande permet d’initialiser Git dans le dossier au sein duquel vous vous trouvez. Cela implique que toutes les opérations que vous réaliserez avec Git dans ce dossier seront sauvegardées.

4- Une fois git initialisé, il faut lui indiquer l’URL du dépôt Github au sein duquel vous souhaitez importer vos fichiers et dossiers.

git remote add origin https://github.com/LeCampionG/github_fiche_rzine.git

Cette url est celle indiquée dans la barre d’adresse de votre navigateur lorsque vous êtes connecté.e à Github et dans votre dépôt. Elle est également indiquée dans les premières informations affichées lorsque vous avez créé votre dépôt.

5- Indiquez les fichiers à téléverser dans le dépôt Github

Cela se fait en plusieurs étapes. D’abord il faut spécifier les fichiers à envoyer.

Les commandes suivantes permettent de préciser les éléments à importer :

  • git add --all : l’intégralité d’un dossier
  • git add rzine_tuto_github.Rmd : un fichier particulier

Dans un second temps, il faut réaliser un commit3, c’est-à-dire une sauvegarde à un instant “t” des différents éléments du dossier et/ou de l’état des fichiers, grâce à la commande git commit.

La commande “-m” suivie d"un texte entre guillemets permet de spécifier le message associé à l’étape d’enregistrement de l’instantané : * git commit -m "1er import des fichiers" * ou simplement -m "un_texte" à la suite d’une commande git commit

6- La dernière étape consiste à rendre tout cela visible et accessible, on parle de pusher4 les fichiers :

  • git push -u origin master, la commande master pointant vers l’endroit où les fichiers seront téléversés.

Notez que pour valider votre import, il faudra fournir votre identifiant et votre mot de passe.

Une fois toutes ces étapes validées, votre dépôt GitHub contiendra les fichiers que vous aviez en local sur votre ordinateur!

Les “Issues” Github

Les issues Github correspondent à un espace d’échange autour de votre projet. C’est un espace ouvert à tous si votre dépôt est public ou seulement à vous-même ou aux personnes auxquelles vous aurez donné accès dans le cas d’un dépôt privé.

La plupart du temps, les issues servent à faire remonter des bugs, signaler des idées de développement, d’amélioration…

Plus que de simples commentaires, il s’agit d’espaces d’échanges à l’image d’un forum. Vous pourrez répondre, commenter, ainsi que maintenir ouverte ou clôturer l’issue.

Pour ouvrir une issue, il faut d’abord se rendre, depuis la page web, du dépôt dans la section correspondante via le bandeau.

Cette page va recenser toutes les issues associées à votre projet. Pour créer et ouvrir une issue, il suffit simplement de cliquer sur New issue.

Vous pourrez donner un titre à votre issue, tagger une personne, donner une étiquette… Une fois rédigée, cliquez sur Submit new issue.

Pour répondre, modifier, clôturer (ou ré-ouvrir) une issue, il suffit de cliquer dessus et réaliser une de ces actions par clic-bouton.

Branche et Pull requests

1.8 Les branches

Git et Github permettent de faire des branches5 Cela s’avère très utile lorsque l’on travaille à plusieurs ou que des corrections de contenu sont nécessaires.

Dans Gitub, la création de branches peut se faire facilement. Depuis l’accueil de votre dépôt (onglet <> code) cliquez sur le bouton encadré en rouge, dans l’image ci-dessous. Ce bouton permet, entre autres choses, de créer des branches.

Un menu déroulant apparait : pour créer une branche, il suffit d’écrire son nom puis de cliquer sur Create branch.

Cet onget vous indiquera dans quelle branche vous vous trouvez et vous permettra également de naviguer entre les branches.

% ICI JE PENSE QUE L’ON PEUT ETRE PLUS CLAIRS En procédant de cette manière, les branches créées seront des copies des branches depuis lesquelles vous les avez produites. Cela suppose que s’il y a des modification à faire il faut les faire depuis Github ou supprimer un fichier et le ré-importer dans la branche. Ce n’est pas toujours le plus efficace.

La même chose est possible en ligne de commande, et, ce, de manière plus optimisée (même si, nous n’aborderons pas ici toute la complexité et les possibilités de la création de branches avec les fonctions Git).

Pour faciliter la compréhension du principe prenons l’exemple de cette fiche Rzine. Nous avons déposé dans un dépôt Github une première version de nos travaux. Nous souhaitons la faire relire par un collègue, ou y apporter nous-même des modifications sans toutefois écraser la première version. Nous allons donc opérer les différentes modifications en local sur notre ordinateur. Une fois satisfaits, nous allons créer une branche au sein de laquelle nous allons importer les fichiers modifiés sans écraser les premiers travaux. Le très grand intérêt à cela c’est que nous pourrons par la suite comparer les deux branches et éventuellement les fusionner.

Commencez par vous placer dans le bon répertoire (ici le dossier tuto_github localisé dans le répertoire Rzine appartenant lui-même au répertoire gregoire et ainsi de suite) :

cd "/mnt/9A8C6DB98C6D9115/gregoire/Rzine/tuto_github"

Pour créer une nouvelle branche (que nous choisissons ici d’appeler “correction”), il suffit d’écrire :

git checkout -b correction

Notons que le répertoire actif bascule alors automatiquement vers la branche nouvellement créée. Il est alors possible d’importer un fichier ou un dossier dans cette nouvelle branche, en suivante la procédure utilisée en amont pour la branche principale :

  • git add rzine_tuto_github.Rmd, pour l’import d’un fichier unique
  • git add --all, pour l’import d’un dossier et de l’ensemble des éléments qu’il contient

% je ne comprends pas ce que tu voulais dire ici : Attention, il est nécessaire d’indiquer à Git quel fichiers ont été retravaillés

La commande git status peut être très pratique pour avoir un aperçu des fichiers qui ont subi des modifications.

Comme précédemment, il faut réaliser un commit, qui permettra notamment de voir et prendre en compte toutes les modifications réalisées sur le fichier :

git commit -m 'fichier sur lequel réaliser les modifications'

Les changements réalisés sur la branche annexe “correction”, s’ils sont validés, peuvent être renvoyés du répertoire local vers une branche du dépôt GitHub (ici, la branche d’origine) :

git push origin correction

Notons, enfin, qu’il est aisé de naviguer d’une branche à l’autre grâce à la commande checkout. Ici, on cherche par exemple à retourner sur la branche master, qui correspond au dernier embranchement dans lequel un commit a été effectué :

git checkout master

1.9 Pull requests

Avec la création de branches, vous pouvez donc modifier comme vous le souhaitez un fichier tout en le conservant intact dans une autre branche.

Une fois les corrections, les modifications… terminées, il peut être utile de comparer les différents éléments et fusionner les fichiers modifiés. On peut alors réaliser un pull request (qui recherche les modifications faites dans les répertoires qui se raccrochent à un dépôt et les fusionne).

Github propose une interface graphique intéressante pour réaliser cette opération (elle est bien évidemment aussi faisable en ligne de commande). Pour ce faire, utilisez le bandeau et cliquez sur le bouton Pull requests.

Cliquez sur New pull request pour lancer une nouvelle comparaison :

Il faut désormais choisir les deux branches à comparer :

Une fois le pull réalisé, vous verrez les différences éventuelles entre vos deux branches : les modifications des fichiers similaires, les fichiers présents dans la 2ème branche mais pas la première…

Si cela vous convient, cliquez sur le bouton Create pull request.

Vous pouvez ensuite commenter, décrire votre demande et la soumettre en cliquant sur Create pull request.

Vous avez donc fait une demande qui apparaitra dans votre section Pull requests.

% pas sûre de comprendre ce que tu voulais dire dans la deuxième partie de la phrase? Vous pouvez échanger des pull request de la même manière qu’avec les issues, avec l’avantage que les pull requests permettent de visualiser ce qui sera fusionné.

Si cela vous convient, vous pouvez accepter les modifications en cliquant sur Merge pull request.

Les deux branches sont alors fusionnées.

Il est également possible de refuser un pull request (et donc d’ignorer les modifications de fichiers associées) en cliquant sur Close pull request

Liste non exhaustive des commandes Git pouvant être utiles

git init : Initialise un nouveau dépôt Git. C’est seulement après avoir entré cette commande que vous pourrez commencer à travailler avec Git.

git config : Raccourci de “configurer”, cette commande est particulièrement utile quand vous paramétrez Git pour la première fois.

git help : Permet d’afficher les 21 commandes les plus courantes de Git. Vous pouvez aussi être plus spécifique et saisir par exemple git help init ou tout autre terme pour voir comment utiliser et configurer une commande spécifique Git.

git status : Vérifie le statut de votre dépôt. Voir quels fichiers sont à l’intérieur, quelles sont les modifications à commiter, et sur quelle branche du dépôt vous êtes en train de travailler.

git add : Cette commande n’ajoute pas de nouveaux fichiers dans votre dépôt. Elle “porte” de nouveaux fichiers à l’attention de Git. Après avoir ajouté des fichiers, ils sont inclus dans les « instantanés » du dépôt Git.

git commit : Une des commandes les plus importante de Git. Après avoir effectué toute sorte de modifications, elle permet de prendre un “instantané” du dépôt (instantané au sens de photographie et donc de sauvegarde).

git push : Si vous travaillez sur votre ordinateur local, et voulez que vos commits soient visibles aussi en ligne sur Github, vous “push”ez les modifications vers Github avec cette commande. Se sont les fichiers portés à l’attention de Git avec git add qui seront “push”ez

git branch : Cette commande vous permet de construire une nouvelle branche, ou une chronologie des commits, des modifications, des ajouts de fichiers…

git checkout : Permet littéralement de vérifier un dépôt dans lequel vous n’êtes pas. C’est une commande de navigation qui vous permet de vous déplacer vers le répertoire que vous voulez vérifier et au sein duquel vous souhaitez travailler. Permet aussi la création d’une branche.

git merge : Lorsque vous avez fini de travailler sur une branche, vous pouvez fusionner vos modifications vers la branche master, qui est visible pour tous les collaborateurs.

git pull : Permet un export en local de la version la plus à jour de votre dépôt.


  1. La gestion ou le conrôle de version renvoie à des pratiques dont l’objectif est de gérer les changements apportés à un fichier (généralement plutôt du code) au fil du temps. Par exemple dans un document de traitement de texte, chaque sauvegarde écrase la précédente. On peut aussi enregistrer une nouvelle version du document qui devient alors un autre fichier complétement indépendant. Les systèmes de contrôle de version permettent quant-à-eux de garder trace de tous les changements réalisés sur un même fichier, comme si l’on prenait et stockait un “instantané” du fichier à chaque étape de modification

  2. Le dépôt/répertoire/repo/repostory est l’espace où vous allez stocker vos fichiers. Il peut être local (le dossier au sein duquel avez enregistré votre fiche Rzine) ou en ligne (l’espace sur Github où vous allez importer vos fichiers). Vous pouvez stocker n’importe quel type de fichier au sein d’un dépôt.

  3. Le commit est l’enregistrement des changements effectués sur un fichier. Il s’agit de l’“instantané”, du point de sauvegarde des changements qui ont été réalisés. C’est sur le commit que repose complétement le système de contrôle de version et donc plus largement les outils comme Git et Github.

  4. Push/“Pusher” est le fait d’envoyer les commits (modifications réalisées) sur le dépôt et donc de les rendre visibles.

  5. Une branche est une ramification indépendante de votre dépôt source. Elle permet donc de modifier en parallèle les fichiers ou la structure du dépôt sans affecter les autres branches. C’est extrêment utile d’autant qu’elles peuvent ensuite être re-fusionnées.